# Literal 用于限制字段值只能是指定的字面量之一（精确匹配）
from typing import Annotated, Literal

from fastapi import FastAPI, Query

# Field 用于为模型字段添加额外的校验规则和元数据
from pydantic import BaseModel, Field

app = FastAPI()


class FilterParams(BaseModel):
    # Field 用于设置默认值和校验规则：
    # - 第一个参数 100 是默认值，若不提供该参数则使用此值
    # - gt=0 表示 "greater than 0"，值必须大于 0
    # - le=100 表示 "less than or equal to 100"，值必须小于等于 100# 作用：确保返回结果数量在 1-100 之间，避免因数量过大导致性能问题
    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)

    # 类型标注为 Literal["created_at", "updated_at"]，表示值只能是这两个字符串之一
    # - "created_at" 表示按创建时间排序# - "updated_at" 表示按更新时间排序
    # 默认值为 "created_at"，若不指定排序方式则默认按创建时间排序
    # 作用：限制排序字段为预定义的合法值，避免传入无效字段导致排序失败
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: Annotated[FilterParams, Query()]):
    return filter_query